home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October : Technology Seed / ATS Oct. '97.toast / Navigation Services SDK 1.0a6 / Interfaces / CIncludes / Navigation.h
Encoding:
C/C++ Source or Header  |  1997-10-31  |  16.6 KB  |  415 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Navigation.h
  3.  
  4.      Copyright:    © 1984-1997 by Apple Computer, Inc.
  5.                  All rights reserved.
  6.  
  7. */
  8. #ifndef __NAVIGATION__
  9. #define __NAVIGATION__
  10.  
  11. #ifndef __TYPES__
  12. #include <Types.h>
  13. #endif
  14. #ifndef __APPLEEVENTS__
  15. #include <AppleEvents.h>
  16. #endif
  17. #ifndef __TRANSLATION__
  18. #include <Translation.h>
  19. #endif
  20. #ifndef __WINDOWS__
  21. #include <Windows.h>
  22. #endif
  23. #ifndef __CODEFRAGMENTS__
  24. #include <CodeFragments.h>
  25. #endif
  26.  
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31. #if PRAGMA_IMPORT_SUPPORTED
  32. #pragma import on
  33. #endif
  34.  
  35. #if PRAGMA_ALIGN_SUPPORTED
  36. #pragma options align=mac68k
  37. #endif
  38.  
  39.  
  40. enum {
  41.     kNavMissingKindStringErr    = -5699,
  42.     kNavInvalidCustomControlMessageErr = -5698,
  43.     kNavCustomControlMessageFailedErr = -5697,
  44.     kNavInvalidSystemConfigErr    = -5696
  45. };
  46.  
  47.  
  48. enum {
  49.     kNavDialogOptionsVersion    = 0,
  50.     kNavReplyRecordVersion        = 0,
  51.     kNavCBRecVersion            = 0,
  52.     kNavFileOrFolderVersion        = 0,
  53.     kNavMenuItemSpecVersion        = 0
  54. };
  55.  
  56. typedef UInt16 NavDataVersion;
  57.  
  58. enum {
  59.     kNavSaveChangesClosingDocument = 1,                            /* closing a document */
  60.     kNavSaveChangesQuittingApplication = 2,                        /* quitting the application */
  61.     kNavSaveChangesOther        = 0                                /* neither closing nor quitting */
  62. };
  63.  
  64. typedef UInt32 NavAskSaveChangesAction;
  65.  
  66. enum {
  67.     askSaveChangesSave            = 1,
  68.     askSaveChangesCancel        = 2,
  69.     askSaveChangesDontSave        = 3
  70. };
  71.  
  72. typedef UInt32 NavAskSaveChangesResult;
  73.  
  74. enum {
  75.     askDiscardChanges            = 1,
  76.     askDiscardChangesCancel        = 2
  77. };
  78.  
  79. typedef UInt32 NavAskDiscardChangesResult;
  80. struct NavFileInfo {
  81.     Boolean                         locked;                        /* file is locked */
  82.     Boolean                         resourceOpen;                /* resource fork is opened */
  83.     Boolean                         dataOpen;                    /* data fork is opened */
  84.     Boolean                         reserved;
  85.     UInt32                             dataSize;                    /* size of the data fork */
  86.     UInt32                             resourceSize;                /* size of the resource fork */
  87.     FInfo                             finderInfo;                    /* more file info: */
  88.     FXInfo                             moreFinderInfo;
  89.     char                             reserved2[212];
  90. };
  91. typedef struct NavFileInfo NavFileInfo;
  92.  
  93. struct NavFolderInfo {
  94.     Boolean                         shareable;
  95.     Boolean                         sharePoint;
  96.     Boolean                         mounted;
  97.     Boolean                         readable;
  98.     Boolean                         writeable;
  99.     Boolean                         reserved;
  100.     UInt32                             numberOfFiles;
  101.     DInfo                             finderInfo;
  102.     DXInfo                             moreFinderInfo;
  103.     char                             reserved2[214];
  104. };
  105. typedef struct NavFolderInfo NavFolderInfo;
  106.  
  107. union FileFolderInfo {
  108.     NavFileInfo                     fileInfo;
  109.     NavFolderInfo                     folderInfo;
  110. };
  111. typedef union FileFolderInfo FileFolderInfo;
  112.  
  113. struct NavFileOrFolderInfo {
  114.     UInt16                             version;
  115.     Boolean                         isFolder;
  116.     Boolean                         visible;
  117.     UInt32                             creationDate;
  118.     UInt32                             modificationDate;
  119.     FileFolderInfo                     fileAndFolder;
  120. };
  121. typedef struct NavFileOrFolderInfo NavFileOrFolderInfo;
  122.  
  123. union eventDataInfo {
  124.     EventRecord *                    event;                        /* for event processing */
  125.     void *                            param;                        /* points to event specific data */
  126. };
  127. typedef union eventDataInfo eventDataInfo;
  128.  
  129. typedef UInt32 NavContext;
  130. struct NavCBRec {
  131.     UInt16                             version;
  132.     NavContext                         context;                    /* used by customization code to call Navigation Services */
  133.     WindowPtr                         window;                        /* the dialog */
  134.     Rect                             customRect;                    /* local coordinate rectangle of customization area */
  135.     Rect                             previewRect;                /* local coordinate rectangle of the preview area */
  136.     eventDataInfo                     eventData;
  137.     char                             reserved[226];
  138. };
  139. typedef struct NavCBRec NavCBRec;
  140.  
  141. typedef NavCBRec *NavCBRecPtr;
  142.  
  143. enum {
  144.     kNavCBEvent                    = 0,                            /* an event has occurred (update, idle events, etc.) */
  145.     kNavCBCustomize                = 1,                            /* protocol for negotiating customization space */
  146.     kNavCBStart                    = 2,                            /* the navigation dialog is starting up */
  147.     kNavCBTerminate                = 3,                            /* the navigation dialog is closing down */
  148.     kNavCBAdjustRect            = 4,                            /* the navigation dialog is being resized */
  149.     kNavCBNewLocation            = 5,                            /* user has chosen a new location in the browser */
  150.     kNavCBShowDesktop            = 6,                            /* user has navigated to the desktop */
  151.     kNavCBSelectEntry            = 7,                            /* user has made a selection in the browser */
  152.     kNavCBPopupMenuSelect        = 8,                            /* signifies that a popup menu selection was made */
  153.     kNavCBAccept                = 9,                            /* user has accepted the navigation dialog */
  154.     kNavCBCancel                = 10                            /* user has cancelled the navigation dialog */
  155. };
  156.  
  157. typedef SInt32 NavEventCallbackMessage;
  158. typedef UInt32 NavCallBackUserData;
  159. /* for events and customization: */
  160. typedef pascal void (*NavEventProcPtr)(NavEventCallbackMessage callBackSelector, NavCBRecPtr callBackParms, NavCallBackUserData callBackUD);
  161. /* for preview support: */
  162. typedef pascal Boolean (*NavPreviewProcPtr)(NavCBRecPtr callBackParms, NavCallBackUserData callBackUD);
  163. /* filtering callback information: */
  164. typedef pascal Boolean (*NavObjectFilterProcPtr)(AEDesc *theItem, void *info, NavContext context, NavCallBackUserData callBackUD);
  165.  
  166. #if GENERATINGCFM
  167. typedef UniversalProcPtr NavEventUPP;
  168. typedef UniversalProcPtr NavPreviewUPP;
  169. typedef UniversalProcPtr NavObjectFilterUPP;
  170. #else
  171. typedef NavEventProcPtr NavEventUPP;
  172. typedef NavPreviewProcPtr NavPreviewUPP;
  173. typedef NavObjectFilterProcPtr NavObjectFilterUPP;
  174. #endif
  175.  
  176. enum {
  177.     uppNavEventProcInfo = kPascalStackBased
  178.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(NavEventCallbackMessage)))
  179.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(NavCBRecPtr)))
  180.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(NavCallBackUserData))),
  181.     uppNavPreviewProcInfo = kPascalStackBased
  182.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  183.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(NavCBRecPtr)))
  184.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(NavCallBackUserData))),
  185.     uppNavObjectFilterProcInfo = kPascalStackBased
  186.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  187.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(AEDesc *)))
  188.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void *)))
  189.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(NavContext)))
  190.          | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(NavCallBackUserData)))
  191. };
  192.  
  193. #if GENERATINGCFM
  194. #define NewNavEventProc(userRoutine)        \
  195.         (NavEventUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavEventProcInfo, GetCurrentArchitecture())
  196. #define NewNavPreviewProc(userRoutine)        \
  197.         (NavPreviewUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavPreviewProcInfo, GetCurrentArchitecture())
  198. #define NewNavObjectFilterProc(userRoutine)        \
  199.         (NavObjectFilterUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavObjectFilterProcInfo, GetCurrentArchitecture())
  200. #else
  201. #define NewNavEventProc(userRoutine)        \
  202.         ((NavEventUPP) (userRoutine))
  203. #define NewNavPreviewProc(userRoutine)        \
  204.         ((NavPreviewUPP) (userRoutine))
  205. #define NewNavObjectFilterProc(userRoutine)        \
  206.         ((NavObjectFilterUPP) (userRoutine))
  207. #endif
  208.  
  209. #if GENERATINGCFM
  210. #define CallNavEventProc(userRoutine, callBackSelector, callBackParms, callBackUD)        \
  211.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppNavEventProcInfo, (callBackSelector), (callBackParms), (callBackUD))
  212. #define CallNavPreviewProc(userRoutine, callBackParms, callBackUD)        \
  213.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppNavPreviewProcInfo, (callBackParms), (callBackUD))
  214. #define CallNavObjectFilterProc(userRoutine, theItem, info, context, callBackUD)        \
  215.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppNavObjectFilterProcInfo, (theItem), (info), (context), (callBackUD))
  216. #else
  217. #define CallNavEventProc(userRoutine, callBackSelector, callBackParms, callBackUD)        \
  218.         (*(userRoutine))((callBackSelector), (callBackParms), (callBackUD))
  219. #define CallNavPreviewProc(userRoutine, callBackParms, callBackUD)        \
  220.         (*(userRoutine))((callBackParms), (callBackUD))
  221. #define CallNavObjectFilterProc(userRoutine, theItem, info, context, callBackUD)        \
  222.         (*(userRoutine))((theItem), (info), (context), (callBackUD))
  223. #endif
  224.  
  225. enum {
  226.     kNavCtlShowDesktop            = 0,                            /*    show desktop,                 parms = nil */
  227.     kNavCtlSortBy                = 1,                            /*    sort key field,             parms->NavSortKeyField */
  228.     kNavCtlSortOrder            = 2,                            /*    sort order,                    parms->NavSortOrder */
  229.     kNavCtlScrollHome            = 3,                            /*    scroll list home,            parms = nil */
  230.     kNavCtlScrollEnd            = 4,                            /*    scroll list end,            parms = nil */
  231.     kNavCtlPageUp                = 5,                            /*    page list up,                parms = nil */
  232.     kNavCtlPageDown                = 6,                            /*    page list down,                parms = nil */
  233.     kNavCtlGetLocation            = 7,                            /*    get current location,        parms<-AEDesc */
  234.     kNavCtlSetLocation            = 8,                            /*    set current location,        parms->AEDesc */
  235.     kNavCtlGetSelection            = 9,                            /*    get current selection,        parms<-AEDescList */
  236.     kNavCtlSetSelection            = 10,                            /*    set current selection,        parms->AEDescList */
  237.     kNavCtlShowSelection        = 11,                            /*    make selection visible,        parms = nil */
  238.     kNavCtlOpenSelection        = 12,                            /*    open view of selection,        parms = nil */
  239.     kNavCtlEjectVolume            = 13,                            /*    eject volume,                parms->vRefNum */
  240.     kNavCtlNewFolder            = 14,                            /*    create a new folder,        parms->StringPtr */
  241.     kNavCtlCancel                = 15,                            /*    cancel dialog,                parms = nil */
  242.     kNavCtlAccept                = 16,                            /*    accept dialog default,        parms = nil */
  243.     kNavCtlIsPreviewShowing        = 17,                            /*    query preview status,        parms<-Boolean */
  244.     kNavCtlAddControl            = 18,                            /*  add one control to dialog,    parms->ControlHandle */
  245.     kNavCtlAddControlList        = 19,                            /*    add control list to dialog,    parms->Handle (DITL rsrc) */
  246.     kNavCtlGetFirstControlID    = 20,                            /*    get 1st control ID,            parms<-UInt16 */
  247.     kNavCtlSelectCustomType        = 21,                            /*    select a custom menu item    parms->NavMenuItemSpec */
  248.     kNavCtlSelectAllType        = 22,                            /*  select an "All" menu item    parms->SInt16 */
  249.     kNavCtlGetEditFileName        = 23,                            /*    get save dialog's file name    parms<-StringPtr */
  250.     kNavCtlSetEditFileName        = 24                            /*    set save dialog's file name    parms->StringPtr */
  251. };
  252.  
  253. typedef SInt32 NavCustomControlMessage;
  254.  
  255. enum {
  256.     kAllKnownFiles                = 0,
  257.     kAllReadableFiles            = 1,
  258.     kAllFiles                    = 2
  259. };
  260.  
  261. typedef UInt16 NavPopupMenuItem;
  262.  
  263. enum {
  264.     kNavSortNameField            = 0,
  265.     kNavSortSizeField            = 1,
  266.     kNavSortDateField            = 2
  267. };
  268.  
  269. typedef UInt16 NavSortKeyField;
  270.  
  271. enum {
  272.     kNavSortAscending            = 0,
  273.     kNavSortDescending            = 1
  274. };
  275.  
  276. typedef UInt16 NavSortOrder;
  277.  
  278. enum {
  279.     kDefaultNavDlogOptions        = 0x000000E4,                    /* use defaults for all the options */
  280.     kNoTypePopup                = 0x00000001,                    /* don't show file type/extension popup on Open/Save */
  281.     kDontAutoTranslate            = 0x00000002,                    /* don't automatically translate on Open */
  282.     kDontAddTranslateItems        = 0x00000004,                    /* don't add translation choices on Open/Save */
  283.     kExtendPopup                = 0x00000008,                    /* extend translation choices on Open/Save */
  284.     kAllFilesInPopup            = 0x00000010,                    /* "All Files" menu item in the type popup on Open */
  285.     kAllowStationery            = 0x00000020,                    /* allow saving of stationery files */
  286.     kAllowPreviews                = 0x00000040,                    /* allow to show previews */
  287.     kAllowMultipleFiles            = 0x00000080,                    /* allow multiple items to be selected */
  288.     kAllowInvisibleFiles        = 0x00000100,                    /* allow invisible items to be shown */
  289.     kDontResolveAliases            = 0x00000200,                    /* don't resolve aliases */
  290.     kSelectDefaultLocation        = 0x00000400                    /* make the default location the browser selection */
  291. };
  292.  
  293. typedef UInt32 NavDialogOptionFlags;
  294.  
  295. enum {
  296.     kNavTranslateInPlace        = 0,                            /*    translate in place, replacing translation source file (default for Save) */
  297.     kNavTranslateCopy            = 1                                /*    translate to a copy of the source file (default for Open) */
  298. };
  299.  
  300. typedef UInt32 NavTranslationOptions;
  301. struct NavMenuItemSpec {
  302.     UInt16                             version;
  303.     OSType                             menuCreator;
  304.     OSType                             menuType;
  305.     Str255                             menuItemName;
  306.     char                             reserved[245];
  307. };
  308. typedef struct NavMenuItemSpec NavMenuItemSpec;
  309.  
  310. typedef NavMenuItemSpec *NavMenuItemSpecPtr;
  311. typedef NavMenuItemSpecPtr *NavMenuItemSpecHandle;
  312. struct NavTypeList {
  313.     OSType                             componentSignature;
  314.     short                             reserved;
  315.     short                             osTypeCount;
  316.     OSType                             osType[1];
  317. };
  318. typedef struct NavTypeList NavTypeList;
  319.  
  320. typedef NavTypeList *NavTypeListPtr;
  321. typedef NavTypeListPtr *NavTypeListHandle;
  322. struct NavDialogOptions {
  323.     UInt16                             version;
  324.     NavDialogOptionFlags             dialogOptionFlags;            /* option flags for affecting the dialog's behavior */
  325.     Point                             location;                    /* top-left location of the dialog, or {-1,-1} for default position */
  326.     Str255                             clientName;
  327.     Str255                             windowTitle;
  328.     Str255                             actionButtonLabel;            /* label of the default button (or null string for default) */
  329.     Str255                             cancelButtonLabel;            /* label of the cancel button (or null string for default) */
  330.     Str255                             savedFileName;                /* default name for text box in NavPutFile (or null string for default) */
  331.     Str255                             message;                    /* custom message prompt (or null string for default) */
  332.     UInt32                             preferenceKey;                /* a key for to managing preferences for using multiple utility dialogs */
  333.     Handle                             popupExtension;                /* extended popup menu items, an array of NavMenuItemSpecs */
  334.     char                             reserved[494];
  335. };
  336. typedef struct NavDialogOptions NavDialogOptions;
  337.  
  338. /* data returned by the utility dialogs: */
  339. struct NavReplyRecord {
  340.     UInt16                             version;
  341.     Boolean                         validRecord;                /* open/save: true if the user confirmed a selection, false on cancel */
  342.     Boolean                         replacing;                    /* save: true if the user is overwriting an existing object for save */
  343.     Boolean                         isStationery;                /* save: true if the user wants to save an object as stationery */
  344.     Boolean                         translationNeeded;            /* save: translation is 'needed', open: translation 'has taken place' */
  345.     AEDescList                         selection;                    /* open/save: list of AppleEvent descriptors of the chosen object(s) */
  346.     ScriptCode                         keyScript;                    /* open/save: script in which the name of each item in 'selection' is to be displayed */
  347.     FileTranslationSpec **            fileTranslation;            /* open/save: list of file translation specs of the chosen object(s), if translation is needed */
  348.     UInt32                             reserved1;
  349.     char                             reserved[231];
  350. };
  351. typedef struct NavReplyRecord NavReplyRecord;
  352.  
  353. extern pascal OSErr NavLoad(void );
  354.  
  355. extern pascal OSErr NavUnload(void );
  356.  
  357. extern pascal UInt32 NavLibraryVersion(void );
  358.  
  359. extern pascal OSErr NavGetDefaultDialogOptions(NavDialogOptions *dialogOptions);
  360.  
  361. extern pascal OSErr NavGetFile(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavPreviewUPP previewProc, NavObjectFilterUPP filterProc, NavTypeListHandle typeList, NavCallBackUserData callBackUD);
  362.  
  363. extern pascal OSErr NavPutFile(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, OSType fileType, OSType fileCreator, NavCallBackUserData callBackUD);
  364.  
  365. extern pascal OSErr NavAskSaveChanges(StringPtr applicationName, StringPtr documentName, NavAskSaveChangesAction action, NavAskSaveChangesResult *reply, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  366.  
  367. extern pascal OSErr NavCustomAskSaveChanges(StringPtr message, NavAskSaveChangesResult *reply, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  368.  
  369. extern pascal OSErr NavAskDiscardChanges(StringPtr documentName, NavAskDiscardChangesResult *reply, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  370.  
  371. extern pascal OSErr NavChooseFile(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavPreviewUPP previewProc, NavObjectFilterUPP filterProc, NavTypeListHandle typeList, NavCallBackUserData callBackUD);
  372.  
  373. extern pascal OSErr NavChooseFolder(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavObjectFilterUPP filterProc, NavCallBackUserData callBackUD);
  374.  
  375. extern pascal OSErr NavChooseVolume(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavObjectFilterUPP filterProc, NavCallBackUserData callBackUD);
  376.  
  377. extern pascal OSErr NavChooseObject(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavObjectFilterUPP filterProc, NavCallBackUserData callBackUD);
  378.  
  379. extern pascal OSErr NavNewFolder(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  380.  
  381. extern pascal OSErr NavTranslateFile(NavReplyRecord *reply, NavTranslationOptions howToTranslate);
  382.  
  383. extern pascal OSErr NavCompleteSave(NavReplyRecord *reply, NavTranslationOptions howToTranslate);
  384.  
  385. extern pascal OSErr NavCustomControl(NavContext context, NavCustomControlMessage selector, void *parms);
  386.  
  387. extern pascal OSErr NavDisposeReply(NavReplyRecord *reply);
  388.  
  389. extern pascal Boolean NavServicesCanRun(void );
  390.  
  391. #if GENERATINGCFM
  392. #ifdef __cplusplus
  393. inline pascal Boolean NavServicesAvailable() { return ((NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress) && NavServicesCanRun()); }
  394. #else
  395. #define NavServicesAvailable()     ((NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress) && NavServicesCanRun())
  396. #endif
  397. #else
  398. pascal Boolean NavServicesAvailable();
  399. #endif
  400.  
  401. #if PRAGMA_ALIGN_SUPPORTED
  402. #pragma options align=reset
  403. #endif
  404.  
  405. #if PRAGMA_IMPORT_SUPPORTED
  406. #pragma import off
  407. #endif
  408.  
  409. #ifdef __cplusplus
  410. }
  411. #endif
  412.  
  413. #endif /* __NAVIGATION__ */
  414.  
  415.